{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "lsymbol_intro_md"
      },
      "source": [
        "# LabeledSymbol"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "lsymbol_desc_md"
      },
      "source": [
        "A `LabeledSymbol` is a specialized version of `gtsam.Symbol` designed primarily for multi-robot applications or scenarios where an additional label is needed besides the type character and index. It encodes a type character (`unsigned char`), a label character (`unsigned char`), and an index (`uint64_t`) into a single 64-bit `gtsam.Key`."
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "lsymbol_colab_md"
      },
      "source": [
        "<a href=\"https://colab.research.google.com/github/borglab/gtsam/blob/develop/gtsam/inference/doc/LabeledSymbol.ipynb\" target=\"_parent\"><img src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Open In Colab\"/></a>"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "lsymbol_pip_code",
        "tags": [
          "remove-cell"
        ]
      },
      "outputs": [],
      "source": [
        "%pip install --quiet gtsam-develop"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 2,
      "metadata": {
        "id": "lsymbol_import_code"
      },
      "outputs": [],
      "source": [
        "import gtsam\n",
        "from gtsam import LabeledSymbol"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "lsymbol_init_md"
      },
      "source": [
        "## Initialization\n",
        "\n",
        "A `LabeledSymbol` can be created by providing a type character, a label character, and an index. It can also be created by decoding an existing `gtsam.Key` (integer)."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "lsymbol_create_code",
        "outputId": "f1a2b3c4-d5e6-7890-f1a2-bcdef1234567"
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "LabeledSymbol from char/label/index: : xA7\n",
            "\n",
            "LabeledSymbol from key 8646911284551352320: : x\n",
            "\n"
          ]
        }
      ],
      "source": [
        "# Create LabeledSymbol 'x' from robot 'A' with index 7\n",
        "# The underlying C++ expects chars, so we have to convert single-character strings with ord()\n",
        "lsym1 = LabeledSymbol(ord('x'), ord('A'), 7)\n",
        "print(f\"LabeledSymbol from char/label/index: {lsym1}\")\n",
        "\n",
        "# Get the underlying integer key\n",
        "key1 = lsym1.key()\n",
        "\n",
        "# Reconstruct LabeledSymbol from the key\n",
        "# Note: Decoding a key assumes it was encoded as a LabeledSymbol.\n",
        "# If you decode a standard Symbol key, the label might be garbage.\n",
        "x0_key = gtsam.Symbol('x', 0).key()\n",
        "lsym2 = LabeledSymbol(x0_key)\n",
        "print(f\"LabeledSymbol from key {x0_key}: {lsym2}\")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "lsymbol_props_md"
      },
      "source": [
        "## Properties and Usage\n",
        "\n",
        "You can access the type character, label character, index, and underlying integer key."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 8,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "lsymbol_access_code",
        "outputId": "a2b3c4d5-e6f7-8901-a2b3-cdef12345678"
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "LabeledSymbol: : lB3\n",
            "\n",
            "  Char (Type): 108\n",
            "  Label (Robot): 66\n",
            "  Index: 3\n",
            "  Key: 7800797504559120387\n"
          ]
        }
      ],
      "source": [
        "robotB_landmark = LabeledSymbol(ord('l'), ord('B'), 3)\n",
        "\n",
        "print(f\"LabeledSymbol: {robotB_landmark}\")\n",
        "print(f\"  Char (Type): {robotB_landmark.chr()}\")\n",
        "print(f\"  Label (Robot): {robotB_landmark.label()}\")\n",
        "print(f\"  Index: {robotB_landmark.index()}\")\n",
        "print(f\"  Key: {robotB_landmark.key()}\")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "lsymbol_shorthand_md"
      },
      "source": [
        "## Shorthand Function\n",
        "\n",
        "GTSAM provides a convenient shorthand function `gtsam.mrsymbol(c, label, j)`."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "lsymbol_shorthand_code",
        "outputId": "b3c4d5e6-f7a8-9012-b3c4-def123456789"
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "LabeledSymbol(ord('p'), ord('C'), 2).key() == gtsam.mrsymbol(ord('p'), ord('C'), 2): True\n"
          ]
        }
      ],
      "source": [
        "pc2_key = gtsam.mrsymbol(ord('p'), ord('C'), 2)\n",
        "\n",
        "print(f\"LabeledSymbol(ord('p'), ord('C'), 2).key() == gtsam.mrsymbol(ord('p'), ord('C'), 2): {LabeledSymbol(ord('p'), ord('C'), 2).key() == pc2_key}\")"
      ]
    }
  ],
  "metadata": {
    "colab": {
      "provenance": []
    },
    "kernelspec": {
      "display_name": "gtsam",
      "language": "python",
      "name": "python3"
    },
    "language_info": {
      "codemirror_mode": {
        "name": "ipython",
        "version": 3
      },
      "file_extension": ".py",
      "mimetype": "text/x-python",
      "name": "python",
      "nbconvert_exporter": "python",
      "pygments_lexer": "ipython3",
      "version": "3.13.1"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 0
}
